\input macros
\def\bookline{\CLOS\  Specification}
\def\chapline{Functions in the Programmer Interface}

\beginChapter 2.{Common Lisp Object System Specification}%
{Functions in the Programmer Interface}{Functions in the Programmer Interface}

Contributors to this document include Daniel G. Bobrow, Linda G.
DeMichiel,\break Richard P. Gabriel, Kenneth Kahn, Sonya E. Keene,
Gregor Kiczales, Larry\break Masinter, David A. Moon, Mark Stefik, and
Daniel L. Weinreb.

Comments and suggestions on this document are encouraged.
Changes will be incorporated over the next several months.
This text will be made available to the X3J13 Committee for the
Common Lisp Standards effort.

\endTitlePage

\beginSection{Introduction}

This chapter describes the functions provided by the \CLOS\
Programmer Interface.    The Programmer Interface comprises the set of 
functions and macros that are sufficient for writing most object-oriented
programs.  

The description of each function includes its purpose, its syntax, the
semantics of its arguments and returned values, and often an example
and cross-references to related functions.  This chapter is reference
material that requires an understanding of the basic concepts of the 
Common Lisp Object System.  The functions are arranged in alphabetic 
order for convenient reference.  

%The Programmer Interface is distinct from the Meta-Object Protocol.
%The Meta-Object Protocol is provided so that systems designers can
%experiment with other object-oriented paradigms, for example, using 
%different rules of inheritance.   

In advance of the alphabetic list of function and macro descriptions, 
it is useful to categorize the functions and macros according to their
role in this standard.

{\it Tools Used for Simple Object-oriented Programming:\/}

These tools allow for defining new classes, methods, generic 
functions, and for making instances.   Some tools used within the body
of methods are also listed here.   Some of the macros listed here have 
a corresponding function that performs the same task at a lower-level of
abstraction. 

{\bf defclass}\break
{\bf make-instance}\break
{\bf defmethod}\break
{\bf defmethod-setf}\break
{\bf defgeneric-options}\break
{\bf defgeneric-options-setf}\break
{\bf call-next-method}\break
{\bf slot-value}\break
{\bf with-slots}\break
{\bf change-class}\break
{\bf class-changed}\break

{\it Functions Underlying the Commonly-Used Macros:\/}

{\bf add-method}\break
{\bf get-method}\break
{\bf get-setf-generic-function}\break
{\bf make-generic-function}\break
{\bf make-method}\break
{\bf remove-method}\break

{\it Tools for Declarative Method Combination:\/}

{\bf define-method-combination}\break
{\bf make-method-call}\break
{\bf method-qualifiers}\break
{\bf multiple-value-prog2}\break
{\bf method-combination-error}\break
{\bf invalid-method-error}\break 

{\it General Common Lisp Support Tools:\/}

{\bf class-of}\break
{\bf describe}\break
{\bf documentation}\break
{\bf print-object}\break 


\vfill
\endSection%{Introduction}


\begincom{add-method}\ftype{Generic function}

\label Purpose:

The generic function {\bf add-method} adds a method to a generic
function.  It destructively modifies the generic function and returns
the modified generic function as its result.

\label Syntax:

\Defgen {add-method} {generic-function method}

\label Arguments:

The {\it generic-function\/} argument specifies a generic function
object.  It is one of the following: a generic function object; a
symbol that names a generic function; or a list that names a 
setf generic function, such as {\tt (setf {\it symbol\/})}.  An error
is signalled if no such generic function exists.

The {\it method\/} argument is a method object.  The argument list of
the method function must be congruent with the argument lists of any
other methods associated with the generic function and with the
lambda list of the generic function.
%[i.e., if there are no other methods, then a defgeneric or
%make-generic must have been performed.  better way to say this?]

\label Values:

The generic function {\bf add-method} returns the modified generic function.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

If the given method is already one of the methods of the generic
function or if the method corresponds in parameter specializers and
method qualifiers to an existing method of the generic
function, an error is signalled.

%Note that a given method may be a method on more than one generic
%function.

\label See Also:

{\bf defmethod

make-method

make-generic-function

defgeneric-options}

\endcom


%\begincom{argument-precedence-order}\ftype{Generic function}
%
%\label Purpose:
%
%The generic function {\bf argument-precedence-order} returns an
%association list.  Each pair in this association list consists of
%a parameter name and an integer that indicates the position of the
%corresponding argument in the precedence order.  A value of 0
%indicates the highest precedence.
%
%\label Syntax:
%
%\Defgen {argument-precedence-order} {generic-function}
%
%\label Arguments:
%
%The {\it generic-function\/} argument is a generic function or a symbol
%that names a generic function.
%
%\label Values:
%
%The result is an association list whose pairs consist of a parameter name
%and an integer that indicates the precedence of the corresponding argument.
%
%\label Examples:
%
%\screen!
%
%[To be written.]
%\endscreen!
%
%\endcom


\begincom{call-next-method}\ftype{Macro}

\label Purpose:

The macro {\bf call-next-method} is used within the body of a method.
It calls the ``next method'' with the same arguments that the current
method received and returns the value or values returned by the method 
it calls.  If there is no next method an error is signalled. 

The type of method combination in use determines in which kinds of
methods {\bf call-next-method} can be used.  The standard method
combination type allows {\bf call-next-method} to be used within primary
methods and {\bf :around} methods and defines the next method as
follows:  if {\bf call-next-method} is used in an {\bf :around} method,
the next method is the next most specific {\bf :around} method if one is
applicable, otherwise it is the next most specific primary method.  If 
{\bf call-next-method} is used in a primary method, the next method is
the next most specific primary method.

%  [The definition of ``next method'' should
% be given in this sentence and the next paragraph deleted.]
%[I did that. --Sonya]

% [so this provides a general imperative form of method combination.] 
%  [I would omit this sentence--what is {\it imperative\/} method combination?]
% [I omitted it.   I believe Imperative means that in the method 
%itself you control the method combination, by imperatively commanding
%that the next method be called.   This is different than declarative
%method combination, which means that elsewhere you declare, or define,  
%a general framework of how methods will be combined.   -Sonya] 
 
\label Syntax:

\Defmac {call-next-method} {}

\label Arguments:

The macro {\bf call-next-method} is used with no arguments.

\label Values:

The macro {\bf call-next-method} returns the value or values
returned by the method it calls.  

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

The macro {\bf call-next-method} passes the current method's original arguments
to the next method.  Neither argument defaulting, nor the use of
{\bf setq} or {\bf let} on variables with the same names as parameters,
affects {\bf call-next-method}.

Further computation after {\bf call-next-method} returns is possible.

If the short form of {\bf define-method-combination} is used to define
a new type of method combination, {\bf call-next-method} can be used
in {\bf :around} methods only. 


\label Possible Extensions: 

{\bf call-next-method} {\it arguments\/}  When at least one argument is
given, {\bf call-next-method} supplies those
arguments instead of the arguments that this method received.  

{\bf apply-next-method} {\it arguments\/} This is like {\bf
call-next-method} except that it uses {\bf apply} instead of {\bf
funcall}.  That is, the last argument is really a list of arguments.

\label See Also:

See the sections ``Method Selection and Combination,''
``Standard Method Combination,'' and ``Declarative Method Combination.''

\endcom



\begincom{change-class}\ftype{Function}

\label Purpose:

The function {\bf change-class} changes the class of an instance to a 
new class.  It destructively modifies and returns the instance.   The values
of slots held in common between the old and new class are preserved in
the new instance.   Any methods for {\bf class-changed} are run.    See Remarks
for details on these aspects of {\bf change-class}, and for a description 
of the restrictions on when {\bf change-class} can be used. 

\label Syntax:

\Defun {change-class} {instance new-class}

\label Arguments:

The {\it instance\/} argument is a Lisp object, although 
not all objects are required to allow {\bf change-class}.   See Remarks below. 

The {\it new-class\/} argument is a class object or a symbol that names
a class. 

\label Values:

The modified instance is returned.  The result of {\bf change-class}
is {\bf eq} to the {\it instance} argument.

\label Examples:

\screen!

(defclass position () ())

(defclass x-y-position (position)
  ((x :initform 0)
   (y :initform 0))
  (:accessor-prefix position-))

(defclass rho-theta-position (position)
  ((rho :initform 0)
   (theta :initform 0))
  (:accessor-prefix position-))

(defmethod class-changed ((old x-y-position) 
                          (new rho-theta-position))
  ;; Copy the position information from old to new to make new
  ;; be a rho-theta-position at the same position as old.
  (let ((x (position-x old))
        (y (position-y old)))
    (setf (position-rho new) (atan y x)
          (position-theta new) (sqrt (+ (* x x) (* y y))))))

\endscreen!

Now the user can make an instance of the class {\tt x-y-position} 
and use {\bf change-class} to change the class of that instance to the class 
{\tt rho-theta-position}:

\screen!

(setq p1 (make-instance 'x-y-position :x 2 :y 0))

(change-class p1 'rho-theta-position)

\endscreen!

The result is that the instance bound to {\tt p1} is now of the class
{\tt rho-theta-position).   The method for {\bf class-changed} took care
of initializing the {\tt rho} and {\tt theta} slots 
properly, based on the value of the X and Y slots 
which were maintained by the old instance.   

\label Remarks:

The \CLOS\ guarantees that {\bf change-class} is allowed for the
following case only:  C1 and C2 are classes that were defined by {\bf  
defclass}, without using the {\bf :metaclass} option in either case.  X
is an instance of class C1. The class of X can be changed from C1 to C2.
Both before and after the call to {\bf change-class}, the metaclass of X
is the default metaclass (that is, {\bf standard-class}). 

Whether {\bf change-class} is allowed for instances of a different
metaclass than the default one is up to the implementor of the
particular metaclass.  Also, whether {\bf change-class} is allowed to
change an object's metaclass is up to the implementors of the two
particular metaclasses.  ``The \CLOS\ Meta-Object Protocol'' will
describe how to control this.

Implementations can choose to support {\bf change-class} in additional
cases if they desire.  For example, this standard does not require that
{\bf change-class} to or from a standard type class is supported;
however it is valid for an implementation to support it for some
standard type classes.

If {\bf change-class} is attempted for any case where the implementation 
does not allow it, an error is signalled. 

{\bf change-class} preserves the values of slots that are common between  
the old and new classes, and initializes any slots that are provided by 
the new class but not the old class.   This behavior is described in 
detail in the section ``Redefining Classes''. 

After completing all other actions, {\bf change-class} invokes the
generic function {\bf class-changed} on two arguments, named {\it
previous\/} and {\it current\/}, representing two views of the instance.
Programmers can define their own methods to initialize new slots  
differently from {\bf make-instance}, or copy information from a slot in
the old instance to a differently-named slot in the new instance.
 
There are two semantic difficulties associated with {\bf change-class}. 
The first problem occurs if an object's class is changed while a generic
function is executing with that object as an argument.  If the object's
class is used for method selection, the currently executing method might
now be the wrong method, not applicable to the object's new class.  No
known \CLOS\ implementation can undo the effects of executing the wrong
method and cause the right method to be executed instead, so the wrong
method simply continues executing.  When a particular generic function
invocation invokes multiple methods because of method combination or
{\bf call-next-method}, an implementation is permitted, but not
required, to decide on the set of methods to be invoked at the beginning
of the generic function invocation.  Thus the set of methods invoked
after the class has been changed is implementation-dependent and not
defined by this standard.

The second semantic difficulty also concerns optimization of slot access; it 
occurs when {\bf change-class} changes the
arrangement in storage of the slots.  
This standard permits, but does not require, an implementation to
compile {\bf with-slots} in an early-binding style.  This means that the
determination of how slots are to be accessed (their memory address and
whether a method needs to be invoked) can be done when the actual slot
access occurs, when the {\bf with-slots} is entered, when the method
containing the {\bf with-slots} is entered, or when the generic function
that invokes the method is called.  This implementation freedom is a
concession to efficiency, which is judged more important than the
semantics of {\bf change-class}.  If the class is changed after the
determination of how slots are to be accessed and before the actual slot
access, the results are undefined.  This means that if a method changes
the class of an argument, that method and any other methods invoked by
the same generic function invocation must not access slots of that 
argument afterwards.

Note that the call to {\bf change-class} that causes semantic difficulties might 
not be lexically visible.  {\bf change-class} could be called by a function that
is called by a method.  All that matters is that the class is changed while
the method is dynamically active. 

Note that in multi-process systems, the semantic difficulties discussed
above occur even when the generic function invocation is in one process and
{\bf change-class} is called in a different process.

This implies that an application programmer must not use {\bf
change-class} inside a method if any methods for that generic function 
access any slots. 

Possible Extension:

We could allow the programmer to avoid the second semantic difficulty by
specifying the implementations must allocate 
slots in order from the least specific class to the most specific (that is,
in the reverse order of precedence).   This implementation strategy 
guarantees that if the methods access only those slots in the common tail
of the class precedence, those slots will not have been moved around in storage. 

Thus the programmer could avoid this difficulty by obeying the following
rules:

If the old and new classes have the same slots, and inherit them from the
same superclasses, then their arrangement in storage will be the same.
This can be accomplished by using mixin classes that do not define any
instance variables of their own, and using {\bf change-class} only to change
which of these mixins are included.  A more complex solution ensures only
that the slots that are actually accessed remain in the same arrangement
in storage.  These slots must be inherited from common superclasses.  The
old and new classes can have additional slots supplied by superclasses
earlier in the precedence list than them.  
This extension would have the advantage that the second semantic difficulty 
never occurs for the implicit call to {\bf change-class} that  
happens when a class is redefined.   

\label See Also:
 
See the section ``Redefining Classes''. 

{\bf class-changed}

\endcom



\begincom{class-changed}\ftype{Generic Function}

\label Purpose:

The generic function {\bf class-changed} is not intended to be called
by programmers.   Its intended use is for programmers to write methods 
on it, which are called automatically by the system in two cases:   
when {\bf defclass} is used to redefine an existing class, and when 
{\bf change-class} is used.   

\label Syntax:

\Defun {class-changed} {previous current}

\label Arguments:

The first argument, {\it previous\/}, is an instance of the old class
created to hold the old slot values temporarily.  Because it has dynamic extent,
it is an error to reference {\it previous\/} in any way after {\bf
class-changed} returns.  The typical use of {\it previous\/} is as an 
argument for {\bf slot-value}, {\bf with-slots}, or an accessor generic 
function, to extract old slot values.  In fact any function, generic or 
not, can receive {\it previous\/} as an argument; thus information about
{\it previous\/} that is not directly stored in slots can be extracted.

The second argument, {\it current\/}, is the instance given as the first
argument to {\bf change-class}.  At the time {\bf class-changed} is 
called it has been fully converted to the new class.

\label Values:

In both cases where {\bf class-changed} is used, the returned value 
is ignored. 

\label Examples:

See the example in the description of {\bf change-class}, where 
a method for {\bf class-changed} is written.  

\label Remarks:

The default method for {\bf class-changed} does nothing.  Programmers
can define their own methods to initialize new slots 
differently from {\bf make-instance}, or copy information from a slot in
the old instance to a differently-named slot in the new instance.
Thus {\bf class-changed} methods can alter the default behavior
of {\bf change-class} with respect to slot value preservation.
The default behavior is described in ``Redefining Classes''. 

The generic function {\bf class-changed} uses standard method 
combination, so {\bf :before}, {\bf :after}, {\bf :around}, and
unqualified methods are allowed. 

\label See Also:

See the section ``Redefining Classes''.

{\bf change-class}

\endcom




\begincom{class-of}\ftype{Function}

\label Purpose:

The function {\bf class-of} returns the class object for the most
specific class of which the given object is an instance.  Every Common
Lisp object has a class.

\label Syntax:

\Defun {class-of} {object}

\label Arguments:

The argument to {\bf class-of} may be any Common Lisp object.

\label Values:

The function {\bf class-of} returns the class object that represents the
most specific class of which the  argument is an instance. 

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

If the object was created with a constructor defined by {\bf defstruct}, 
the class that is returned is the class with the same name as the data
type defined with the {\bf defstruct} form.

If the object is an instance of a class whose class is {\bf
standard-type-class} or a subclass of {\bf standard-type-class} (other 
than a class created with {\bf defstruct}), the class that is returned
is the most specific class according to Figure~1-2.

\endcom



\begincom{defclass}\ftype{Macro}

\label Purpose:

The macro {\bf defclass} defines a new class.  It returns the name of
the new class as its result.

The syntax of {\bf defclass} provides options for specifying default
initialization values for slots and for requesting that functions be
automatically generated to read and write the values of slots and to
construct new instances.  No accessor, reader, or constructor
functions are defined by default; their generation must be explicitly 
requested.  No initial slot values are provided by default. 

Defining a new class also causes a type of the same name to be defined. 
The predicate {\tt (typep {\it object class-name\/})} is true if the
class of the given object is {\it class-name\/} itself or a superclass
of the class {\it class-name\/}.   

\eject
\label Syntax:

\cboxfig{
\leftskip 2pc
\cleartabs\settabs\+\hskip\leftskip&\cr
\+&{\bf defclass} {\it class-name} \paren{\star{\curly{superclass-name}}}
\paren{\star{\curly{slot-spec}}} \star{\curly{class-option}}\cr
\Vskip 1pc!
\+&{\it class-name\/}::$=$ {\it symbol\/}\cr
\Vskip 1pc!
\+&{\it superclass-name\/}::$=$ {\it symbol\/}\cr
\Vskip 1pc!
\+&\cleartabs{\it slot-spec\/}::$=$ &{\it slot-name\/} $\vert$ ({\it slot-name\/} \star{\curly{slot-option}})\cr
\Vskip 1pc!
\+&{\it slot-name\/}::$=$ {\it symbol\/}\cr
\Vskip 1pc!
\+&\cleartabs{\it slot-option\/}::$=$ &{\tt :accessor} {\it generic-function-name\/} $\vert$ \cr
\+&&{\tt :reader} {\it generic-function-name\/} $\vert$ \cr
\+&&{\tt :allocation} {\it allocation-type\/} $\vert$ \cr
\+&&{\tt :initform} {\it form\/} $\vert$ \cr
\+&&{\tt :type} {\it type-specifier\/} \cr
\Vskip 1pc!
\+&{\it generic-function-name\/}::$=$ {\it symbol\/}\cr
\Vskip 1pc!
\+&{\it allocation-type\/}::$=$ {\tt :instance $\vert$ :class $\vert$ :dynamic $\vert$ :none}\cr
\Vskip 1pc!
\+&\cleartabs{\it class-option\/}::$=$ &({\tt :accessor-prefix} {\it string-or-symbol\/}) $\vert$\cr
\+&&({\tt :reader-prefix} {\it string-or-symbol\/}) $\vert$\cr
\+&&({\tt :constructor} {\it symbol\/} \brac{boa-arglist\/}) $\vert$\cr
\+&&({\tt :documentation} {\it string\/}) $\vert$ \cr
\+&&({\tt :metaclass} {\it class-name\/}) \cr
\Vskip 1pc!
\+&\cleartabs{\it boa-arglist\/}::$=$ (& \star{\curly{symbol}}\cr
\+&&\ttbrac{{\opt} \star{\curly{var $\vert$ {\rm (}var \ttbrac{initform}{\rm )}}}}  \cr
\+&&\ttbrac{{\rest} {\it var}}\cr
\+&&\ttbrac{{\tt\&aux} \star{\curly{var $\vert$ {\rm (}var \brac{initform}{\rm )}}}}{\rm )}\cr
}
\caption{Syntax for defclass}
\endfig

\vfill\eject


\label Arguments:

The {\it class-name\/} argument is a non-{\bf nil} symbol.  It becomes the 
name of the new class.  If a class with the same name already exists, the
definition of that class is replaced.

Each {\it superclass-name\/} argument is a non-{\bf nil} symbol.
The new class will inherit slots and methods from each of its superclasses,
from their superclasses, and so on.

Each {\it slot-spec\/} argument is the name of the slot or a list consisting
of the slot name followed by zero or more slot options.  The {\it slot-name\/}
argument is a symbol that can be used as a Common Lisp variable name.   
There must not be any duplicate slot names. 

The following {\it slot-options\/} are available:

\beginlist

\item{\bull} 
The {\bf :accessor} {\it generic-function-name\/} option 
specifies that an unqualified method is to be
defined on the generic function named {\it generic-function-name\/} to
read the value of the given slot and that a method is to be defined on the
setf generic function named {\it generic-function-name} to be
used with {\bf setf} to modify the value of the slot.
The {\it generic-function-name\/} argument is a non-{\bf nil} symbol.
The {\bf :accessor} option may be specified more than once for a given
slot.

\item{\bull}
The {\bf :reader} {\it generic-function-name\/} option specifies 
that an unqualified method is to be
defined on the generic function named {\it generic-function-name\/}
to read the value of the given slot.  The {\it
generic-function-name\/} argument is a non-{\bf nil} symbol.  The {\bf
:reader} option may be specified more than once for a given slot.

\item{\bull}
The {\bf :allocation} {\it allocation-type\/} option is 
used to specify where storage is to be 
allocated for the given slot.  Storage for a slot may be static or dynamic;
it may be located in the class instance or in the class object itself.
The value of the {\it allocation-type\/}
argument can be one of the following keywords: {\bf :instance}, {\bf :class},
{\bf :dynamic}, or {\bf :none}.  The {\bf :allocation} option may be
specified at most once for a given slot.  If the {\bf :allocation} option
is not specified, storage for the slot is allocated in the class instance.

\beginlist

\itemitem{--}
If {\it allocation-type\/} is {\bf :instance}, storage for the slot is allocated
in each instance of the class.  

\itemitem{--}
If {\it allocation-type\/} is {\bf :class}, storage for the slot is allocated
in the class object created by this {\bf defclass} form.  The value of
the slot is shared by all instances of the class.  Any subclass of this 
class will share this single slot unless the {\bf defclass} form 
for that subclass specifies a slot of the same name.   
 
\itemitem{--}
If {\it allocation-type\/} is {\bf :dynamic}, storage is allocated in the instance
the first time the slot is used.  This option allows infrequently-used slots
to occupy storage only if necessary.
%If the slot is initialized with a keyword
%argument to {\bf make-instance}, the slot is allocated then.  If the
%first access is a read, then storage is allocated and the default value
%specified in the {\bf defclass} form, if any, is stored in the slot and
%returned.  If the first access is a {\bf setf}, then storage is
%allocated and the value is stored in the slot and returned.  

\itemitem{--}
If {\it allocation-type\/} is {\bf :none}, instances of this class cannot
access this slot (although the slot may exist, if a superclass
allocated storage for it). 

\endlist 

\item{\bull}
The {\bf :initform} {\it form\/} option is used to provide
an initial value form to be used in the initialization of the
slot.  The {\bf :initform} option may be specified at most once for a
given slot.    This form is evaluated every time it is used.  
The lexical environment in which this form is evaluated is the 
lexical environment in which {\bf defclass} was evaluated.
Note that the lexical environment refers both to variables and to functions. 
The dynamic environment is the one in effect at the time the form is evaluated.
This is the same behavior specified in {\it Common Lisp the Language\/} 
for {\bf defstruct} slot initialization forms. 

%I removed this according to the mail.  -Sonya
%If we put it back in, the Syntax line for it was:
%\+&&{\tt :initialize-only} {\it flag\/} $\vert$\cr
%Also, must decide if it be given more than once per slot, or not?
%\item{\bull}
%The {\bf :initialize-only} option is used to specify that the contents
%of the given slot may not be altered after the instance is created.
%The default value of the {\bf :initialize-only} option is {\bf nil}.

\item{\bull}
The {\bf :type} {\it type-specifier\/} option specifies 
the type of the slot contents.  The expression 
{\tt ({\bf typep} {\it value type-specifier\/})} must be true for the
value stored in the slot.  
The {\bf :type} option may be specified at most once for a given slot. 

%\item{\bull}
%The {\bf :initable} option specifies a non-{\bf nil} symbol to be used
%to specify an initial value of this slot, when a new instance is being
%made.  This symbol can be supplied as an {bf \&key} argument to {bf
%make-instance}.  (This is still under discussion.) 
%The {\bf :initable} option may be specified more than once for a given slot.

\endlist

Each {\it class-option\/} is an option that refers to the class as a whole
or to all class slots.
The following options are available:

\beginlist
\item{\bull}
The {\bf :accessor-prefix} option specifies that, for each
slot, an unqualified method to read the value of the slot is to be defined on the 
generic function named {\it string-or-symbol}{\bf -} followed by the
name of the slot.  Similarly, a method to be used with the macro {\bf
setf} to modify the value of the slot is to be defined on the setf
generic function named {\it string-or-symbol}{\bf -} followed by the
name of the slot.  These accessor functions are interned in the
package that is current at the time the {\bf defclass} form is
macro-expanded.  If the prefix is {\bf nil}, the names of the accessor
functions are the symbols that are used as the slot names.  The {\bf
:accessor-prefix} option may be specified more than once.

\item{\bull} 
The {\tt ({\bf :reader-prefix} {\it string-or-symbol\/})} option 
specifies that for each slot, an unqualified  
method to read the value of the slot is to be defined
on the generic function named {\it string-or-symbol}{\bf -} followed by
the name of the slot.  These reader functions are interned in the
package that is current at the time the {\bf defclass} form is
macro-expanded.  If the prefix is {\bf nil}, the names of the reader
functions are the symbols that are used as the slot names.  The {\bf
:reader-prefix} option may be specified more than once.

\item{\bull}
The {\tt ({\bf :constructor} {\it symbol [boa-arglist]\/})} option causes a 
constructor function to be 
generated automatically.  The constructor function is used to make
new instances of the class.
The {\it symbol\/} argument is a non-{\bf nil} symbol that
specifies the name of the constructor function.
If the {\it boa-arglist\/} argument is present, it describes the arguments
to the constructor.  The {\it boa-arglist\/} argument of {\bf defclass}
is the same as that of {\bf defstruct}.
% [We need to decide what should *really* be done here:]
%, with some additions.   Here,
%{\bf \&key} and {\bf \&allow-other-keys} are allowed, as are supplied-p
%parameters. 
The {\bf :constructor} option may be specified more than once.

%\item{\bull}
%[The following is still under discussion:]
%The {\bf :default-init-plist} option is used to specify default values
%that are to be used when making an instance of the class.  For
%example, a class might specify a default value to use to initialize a

%must be a valid keyword argument to {\bf make-instance}.  Each {\it
%argument\/} is a form that provides the default value for that keyword
%argument if it is not supplied.  The user can override the defaults in
%the {\bf :default-init-plist} by providing keyword arguments to {\bf
%make-instance}.  The {\it arguments\/} are evaluated every time they
%are used.  The {\bf :default-init-plist} option may be specified more
%than once.  This option is still under discussion; it is not yet clear
%whether it should be in the standard.

\item{\bull} 
The {\tt ({\bf :documentation} {\it string\/})} option 
attaches a documentation string to the class name. 
The documentation type for this string is {\bf type}.  
The form {\tt (documentation {\it class-name\/} 'type)} 
may be used to retrieve the documentation 
string.  The {\bf :documentation} option may be specified at most once. 

%\item{\bull}
%[The following is still under discussion:]
%The {\bf :init-keywords} option is used to
%specify that the given keywords may be used as keyword arguments to
%{\bf make-instance} when an instance of this class is to be created.
%It is not necessary to provide this argument to make it possible
%to initialize slots; that is done with the {\bf :initable-slots} option.
%The {\bf :init-keywords} option is used in conjunction with user-supplied
%methods {\bf make-instance}.  If a {\bf make-instance} method accepts
%an argument, it must be made an allowed keyword argument to {\bf make-instance}
%by using this option.
%The {\bf :init-keywords} option may be specified more than once.

%\item{\bull}
%[The following is still under discussion:]
%The {\bf :initable-slots} option is used to specify that it is allowed
%to initialize all
%slots of this class.  The initialization can be done by providing the
%keyword with the same name as the slot, followed by the slot's initial
%value as an argument to {\bf make-instance} or by including the keyword
%and value in the {\bf :default-init-plist}.

%\item{\bull}
%[Omitted because both Moon and Gregor thought it ought to go.  -Sonya]
%The {\bf :uninstantiable} option is used to specify whether it is
%possible to directly instantiate the new class with {\bf make-instance}.
%If the value of {\bf :uninstantiable} is true, the class cannot be instantiated
%and is termed an {\bit abstract class}.  The default value of {\bf
%:uninstantiable} is {\bf nil}.  The {\bf :uninstantiable} option may be 
%specified at most once.

\item{\bull}
The {\tt ({\bf :metaclass} {\it class-name\/})} option 
is used to specify that instances of the class being defined 
are to have a different metaclass than the default provided by the 
system (the class {\bf standard-class}).  The {\it class-name} argument is the
name of the desired metaclass.  The {\bf :metaclass} option may be 
specified at most once. 

%\item{\bull}
%The {\bf :predicate} option causes a predicate function
%named {\it symbol\/} to be generated automatically.  The {\it
%symbol\/} argument must be a non-{\bf nil} symbol.  The predicate
%function takes one argument, an object.  It returns true if the object
%is of this class, otherwise it returns {\bf nil}.  The {\bf :predicate}
%option may be specified more than once.

\endlist

\label Values:

The name of the new class is returned as the result.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

If a class of the same name already exists, that class is redefined and
instances of the class (and subclasses of it) are updated to the new
definition, at the time that they are next accessed.   For details,
see ``Redefining Classes'' and {\bf change-class}.  

It is not allowed to redefine a standard type class.  

%\beginlist
%\item{\bull}
%A copy of the class object is created.  This copy is named {\tt
%|obsolete-{\it class-name\/}|}, where {\it class-name\/} is the name of
%the original class; this copy is {\bf equal} to the original class
%object.
%
%\item{\bull}
% All instances of the original class are made to point to the
%``obsolete'' class object.
%
%\item{\bull}
%The original class object is modified to reflect the specified
%changes; this modified class object is {\bf eq} to the original.
%
%\item{\bull}
%When an instance of the obsolete class 
%is accessed, it is updated to reflect the new class definition.
%
%\endlist

%Each class has a superclasses lattice composed of all its immediate
%superclasses, the immediate superclasses of these superclasses, and so
%on.  This lattice is used to compute the class precedence list of the
%class.  It is discussed in the section ``Determining the Class
%Precedence List.''

Note the following rules of {\bf defclass}:

\beginlist

\item{\bull}
It is not required that the superclasses of a class be defined before
the {\bf defclass} form for that class is evaluated.

\item{\bull}
All the superclasses of a class must be defined before it is permitted
to make an instance of the class.

\item{\bull}
A class must be defined before it can be used as a parameter
specializer in a {\bf defmethod} form.

\item{\bull}
All the superclasses of a class must be defined before it is
permitted to evaluate or compile a {\bf with-slots} form that uses that class.

\endlist

Some slot options are inherited by a class from its 
superclasses, and some can be overridden or altered by providing a
local slot description.   No class options are inherited.  For a 
detailed description of how slots and slot options are inherited,
see ``Inheritance''. 

Some implementations might add other options to {\bf defclass}.
Therefore it is required that all implementations signal an error if
they observe a class option or a slot option that is not implemented
locally.

If no default value for a slot is specified either in a {\bf
defclass} or a {\bf make-instance} form, the initial value of the
slot is unspecified.

It is valid to specify more than one accessor, reader, and initialization
keyword for a slot.

If neither a reader nor an accessor is specified for a slot, the slot
can only be accessed by the function {\bf slot-value} or {\bf
with-slots} using {\bf :use-accessors nil}.

The {\bf :accessor-prefix}, {\bf :constructor}, and {\bf :reader-prefix}
class options may appear more than once.  No other class option may 
appear more than once in a single {\bf defclass} form.  No other slot 
option may appear more than once in a single slot description. 

\label See Also:

{\bf slot-value

with-slots}

``Classes''

``Inheritance''

``Determining the Class Precedence List''

\endcom



\begincom{defgeneric-options}\ftype{Macro}

\label Purpose:

The macro {\bf defgeneric-options} is used to specify options and
declarations that pertain to a generic function as a whole.

The generic function is stored in the symbol-function cell of {\it name}.
If {\tt (fboundp {\it name\/})} is {\bf nil}, a new generic function 
is created.  If {\tt (symbol-function {\it name\/})} is a generic function,
that generic function is modified.  If neither of these conditions holds,
{\bf defgeneric-options} signals an error.

The macro {\bf defgeneric-options} returns {\it name\/} as its result.

\label Syntax:

\Defmac {defgeneric-options} {name lambda-list \star{\curly{option}}}

{\it option\/}::$=$ {\tt\vtop{\hbox{(:argument-precedence-order \plus{\curly{parameter-name}}) $\vert$}
\hbox{(declare \plus{\curly{declaration\/}}) $\vert$}
\hbox{(:documentation {\it string\/}) $\vert$}
\hbox{(:method-combination {\it symbol\/} \star{\curly{args\/}}) $\vert$}
\hbox{(:generic-function-class {\it class-name\/}) $\vert$}
\hbox{(:method-class {\it class-name\/})}}}

\label Arguments:

The {\it name} argument is a non-{\bf nil} symbol.

The {\it lambda-list\/} argument is an ordinary function lambda list
with these exceptions:

\beginlist
\item{\bull}
No {\bf \&aux} variables are allowed. 

\item{\bull}
Optional and keyword arguments may not have default initial value forms
or use supplied-p parameters.
The generic function passes to the method all the argument values passed to
it and only those; default values are not supported.
Note that optional and keyword arguments in method definitions, however,
can have default initial value forms and can use supplied-p parameters. 
\endlist

The following {\it options\/} are provided:

\beginlist

\item{\bull} The {\bf :argument-precedence-order} option 
is used to specify the order order in which 
the required arguments in a call to the generic function are tested for
specificity when selecting a particular method.  By default, all
required arguments are considered from left to right; each required
argument has precedence over those to its right.   Each required 
argument should be included exactly once as a {\it parameter-name}, so
the full and unambiguous precedence order is supplied.   If this
condition is not met an error is signalled.

\item{\bull} The {\bf declare} option is used to specify declarations
that pertain to the generic function.  These declarations do not apply
to the methods.  The only declaration required in this standard is
{\bf optimize}, which can have the value of {\bf speed} or {\bf space}.  This
allows the user to control whether method selection is optimized for
speed or space, but has no effect on individual methods.  Declarations
that have semantic effect ({\bf special}, {\bf inline}, and {\bf
notinline} declarations) are not permitted.  Other types of
declarations are advice to the compiler that may or may not affect the
implementation of the generic function.  Individual implementations
are not required to implement them.  If an implementation notices a
declaration that it does not support and that has not been proclaimed
as a non-standard declaration name, it should issue a warning.  

\item{\bull} The {\bf :documentation} argument associates a
documentation string with the generic function.   The documentation type
for this string is {\bf function}.  The form {\tt (documentation {\it
generic-function-name\/} 'function)} may be used to retrieve this
string.

\item{\bull} The {\bf :generic-function-class} option may be used to specify that
the generic function is to have a different class than the default provided
by the system (the class {\bf standard-generic-function}).
The {\it class-name\/} argument is the name
of a class that can be the class of a generic function.

%\item{\bull}
%The {\bf :interface} option is still under discussion.
%[The meaning of this stuff isn't clear enough to me for me to be
%able to rewrite it:
%                Defines a function that runs instead of the generic
%                dispatch.  This is completely transparent to anyone calling
%                the generic function.  Such a prologue function can be used
%                to rearrange the arguments, to standardize the arguments
%                before the methods see them, to default optional arguments,
%                to do the shared non-generic portion of an operation, or
%                for any other purpose.
%
%                Inside the forms you can trigger the generic dispatch with
%                (call-next-method args...) or (apply-next-method args...).
%               apply-next-method treats the last argument as a list of
%                arguments just like apply.  ]
%
%\item{\bull}
%(:method-arguments {lambda-list}+)
%[The meaning of this stuff isn't clear enough to me for me to be
%able to rewrite it:
%               This option is under discussion. 
%                You can use this option to specify that the methods accept
%                different arguments than does the generic function itself.
%                By default, the methods receive the same arguments that are
%                specified at the top of the defgeneric form.   If
%               :interface is also specified, it provides the
%               translation from generic-function arguments to 
%               method-arguments.   If :interface is not specified, the
%               arguments are permuted according to matching names, and
%               all names in the :method-arguments lambda-list must also
%               appear in the generic-function's lambda-list.   For
%                example:
%                       
%               (defgeneric foo (x y \&optional z) 
%                   (:method-arguments y x z)) ]

\item{\bull} The {\bf :method-class} option is used to specify that all methods for
this generic function are to have a different class than the default
provided by the system (the class {\bf standard-method}).
The {\it class-name\/} argument is the name of a
class that is capable of being the class of a method.

\item{\bull} The {\bf :method-combination} option is followed by a symbol that 
names a type of method combination.   The arguments (if any) that follow 
that symbol depend on the type of method combination.   Note that the
standard method combination type does not support any arguments.
However, all types of method combination defined by the short form of {\bf 
define-method-combination} accept an optional argument named {\it 
order\/}, defaulting to {\bf :most-specific-first}.  A value of {\bf
:most-specific-last} reverses the order of the primary methods, without
affecting the order of the auxiliary methods.

\endlist

\label Values:

The macro {\bf defgeneric-options} returns {\it name\/} as its result.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

[What happens when {\bf defgeneric-options} causes the options of an existing
generic function to be changed needs to be spec'd out.]

If a {\bf defgeneric-options} form is evaluated and some methods for that
generic function have parameters that are not congruent with those
listed in the {\bf defgeneric-options}, an error is signalled.  

[Note:  other kinds of errors still need to be discussed.]

%No -- this just needs a cross reference to the Concepts
%section that describes it.    Shouldn't duplicate it here.  -Sonya
%[Needs discussion about compatibility of methods.]
Congruent Lambda-lists for all Methods of a Generic Function

Some implementations might add other options to {\bf defgeneric-options}. 
Therefore it is required that all implementations signal an error if
they observe an option that is not implemented locally.

\label See Also:

``Congruent Lambda-lists for all Methods of a Generic Function'' 

\endcom




\begincom{defgeneric-options-setf}\ftype{Macro}

\label Purpose:

The macro {\bf defgeneric-options-setf} is used to define a setf
generic function.  A setf generic function is called in an
expression such as {\tt (setf ({\it name arguments}) {\it new-value})}.

The macro {\bf defgeneric-options-setf} returns {\it name\/} as its result.

\label Syntax:

\Defmac {defgeneric-options-setf} {name lambda-list setf-lambda-list \star{\curly{option}}}

{\it setf-lambda-list\/}::$=$ \paren{variable-name\/}
\Vskip 1pc!
{\it option\/}::$=$ {\tt\vtop{\hbox{(:argument-precedence-order  \plus{\curly{parameter-name}}) $\vert$}
\hbox{(declare \plus{\curly{declaration\/}}) $\vert$}
\hbox{(:documentation {\it string\/}) $\vert$}
\hbox{(:method-combination {\it symbol\/} \star{\curly{args\/}}) $\vert$} 
\hbox{(:generic-function-class {\it class-name\/}) $\vert$}
\hbox{(:method-class {\it class-name\/})}}}
\Vskip1pc!\null

\label Arguments:

The {\it name\/} argument is a non-{\bf nil} symbol. 

The {\it lambda-list\/} argument is identical to the
{\it lambda-list\/} argument of {\bf defgeneric-options}.

The keyword options are the same as for {\bf defgeneric-options}.

\label Values:

The macro {\bf defgeneric-options-setf} returns {\it name\/} as its result.

\label Examples:

\screen! 

[To be written.]
\endscreen!



\label Remarks:

[The internal operation of this function needs to be spec'd out.
%--Gregor to provide.
]

%Cross reference is adequate.   No need to duplicate it here.  -Sonya
%[Needs discussion about compatibility of methods.]

\label See Also:

{\bf defgeneric-options

defmethod}

``Congruent Lambda-lists for all Methods of a Generic Function'' 

\endcom




\begincom{define-method-combination}\ftype{Macro}

\label Purpose:

The macro {\bf define-method-combination} is used to define new types
of method combination.    The syntax and semantics of {\bf define-method-combination}
are described in ``Declarative Method Combination,'' along with several 
examples of its use.

\label Syntax:

Short form:

\Defmac {define-method-combination} {name operator \star{\curly{keyword argument}}}

Long form:

\screen! 

[To be TEXed.]

(DEFINE-METHOD-COMBINATION name lambda-list                     [macro]
      ( {(variable { {qualifier-pattern}+ | predicate}
                   {keyword argument}*)}* )
  {declaration | doc-string}*
  {form}*)

\endscreen!

\label Arguments:

In both the short and long forms, {\it name\/} is a symbol, usable as a
name for this in the {\bf :method-combination} option to {\bf
defgeneric-options} or {\bf defgeneric-options-setf}.  By convention,
non-keyword, non-{\bf nil} symbols are usually used.

The short form syntax of {\bf define-method-combination} is recognized
when the second subform is a non-{\bf nil} symbol.  {\it operator\/} is
a symbol that can be the name of a function, macro, or special form.
When the short form is used, {\it name\/} is defined as a type of method
combination that produces a Lisp form {\bf ({\it operator method-call
method-call...\/})}.

Keyword options for the short form are:

\beginlist

\item{\bull}
{\bf :documentation} {\it string\/} documents the method-combination type.

\item{\bull}
{\bf :identity-with-one-argument} {\it boolean\/} enables an optimization 
when {\it boolean\/} is true (the default is false). 
If there is exactly one applicable method, and it is a primary method,
that method serves as the effective method and {\it operator\/} is not called.
Use this option with operators such as {\bf progn}, {\bf and}, {\bf $+$}, 
and {\bf max}.  

\endlist

None of the subforms is evaluated.

The long form syntax of {\bf define-method-combination} is recognized 
when the second subform is a list.  

The syntax of the long form is covered only briefly here.   It is explained
fully in the section ``Declarative Method Combination''. 

{\it lambda-list\/} is an ordinary lambda-list.  The first argument it 
receives is the generic-function.  It also receives any arguments provided
after {\it name\/} in the {\bf :method-combination} option to 
{\bf defgeneric-options} or {\bf defgeneric-options-setf}.

A list of method-group specifiers follows.  Each specifier selects a subset
of the applicable methods to play a particular role, either by matching
their qualifiers against some patterns or by testing their qualifiers with
a predicate. 

Each method-group specifier names a {\it variable\/}.  During the
execution of the body forms, this variable is bound to a list of the
methods in the method-group, in most specific first order.

A qualifier-pattern is a list or the symbol {\bf *}

The name of a predicate function can appear in place of the
qualifier-patterns in a method-group specifier.  A predicate is
distinguishable from a qualifier-pattern because it is a symbol other
than {\bf nil} or {\bf *}. 

Method-group specifiers can have keyword options after the
qualifier-patterns or predicate.  Keyword options are distinguishable from
additional qualifier patterns because they are not lists nor the symbol
{\bf *}.  The keyword options are:

\numitem{{\bf :description} {\it format-string\/}} \break
Programming environment tools use
% TEX won't let me use #' in the next line
{\bf (apply (function format) stream {\it format-string\/}
(method-qualifiers {\it method\/}))}
to print a concise description of a method's role (one or two words). 
The argument {\it format-string\/} is not evaluated. 

\numitem{{\bf :order} {\it order\/}} \break
The argument is a form evaluating to {\bf :most-specific-first} or
{\bf :most-specific-last}.  If it evaluates to any other value,
an error is signalled.  
If {\bf :order} is not specified, it defaults to {\bf :most-specific-first}.

\numitem{{\bf :required} {\it boolean\/}} \break
If {\it boolean\/} is true (not {\bf nil}), and the method-group is empty
(that is, no applicable methods match the qualifier-patterns or satisfy the
predicate), an error is signalled.  
If {\bf :required} is not specified, it defaults to {\bf nil}. 
The argument {\it boolean\/} is not evaluated. 
\def\numhangsize{25pt}

\label Values:

The name of the new method combination type is returned. 

\label Examples:

Most examples of the long form of {\bf define-method-combination} also illustrate 
the use of the related functions that are provided as part of the declarative
method combination facility.   Thus examples of all of these are provided 
in the section ``Examples of the Long Form of Define-method-combination''.  

\label Remarks: 

To specify that a generic function should use this type of method combination, use
the {\bf (:method-combination {\it name\/})}
option to {\bf defgeneric-options} or {\bf defgeneric-options-setf}.

Individual implementations might support other keyword options.
Therefore it is required that all implementations signal an error if
they observe a keyword option that is not implemented locally.

 
\label See Also: 

{\bf make-method-call}

{\bf method-qualifiers}

{\bf multiple-value-prog2}

{\bf method-combination-error}

{\bf invalid-method-error} 

\endcom



\begincom{defmethod}\ftype{Macro}

\label Purpose:

The macro {\bf defmethod} defines a method on a generic function.  

If a generic function is currently named by the symbol {\it name\/}, 
the argument list of the method must be congruent with the lambda 
list of the generic function.  If this condition does not hold, an error is 
signalled.  See ``Generic Functions and Methods'' for 
a definition of congruency in this context.  

If no generic function is currently named by the symbol {\it name\/}, a
generic function is created with default values for the argument
precedence order (each argument is more specific than the arguments to 
its right in the argument list), the generic function class (the class
{\bf standard-generic-function}), the method class (the 
class {\bf standard-method}), and 
the standard method combination type.  The lambda list of the  
generic function is congruent with the argument list of the method being
defined.

If the symbol {\it name\/} names a non-generic function, a macro, or a
special form, an error is signalled.

\label Syntax:

\Defmac {defmethod} {name
\vtop{\hbox{\star{\curly{method-qualifier\/}}}
\hbox{specialized-lambda-list}
\hbox{\star{\curly{declaration $\vert$ documentation}} \star\form}}}
\Vskip1pc!\null
{\it name\/}::$=$ {\it symbol}
\Vskip1pc!\null
{\it method-qualifier\/}::$=$ {\it symbol}
\Vskip1pc!\null
\settabs\+\hskip\leftskip&\cr
\+&{\it specialized-lambda-list\/}::$=$ (&\star{\curly{var  $\vert$ {\rm (}var specializer\/{\rm )}}}  \cr
\+&&\ttbrac{{\opt} \star{\curly{var $\vert$ {\rm (}var \ttbrac{initform {\brac{supplied-p-parameter}} }{\rm )}}}}  \cr
\+&&\ttbrac{{\tt\&rest} {\it var\/}} \cr
\+&&{\tt [}{\key{}}&\star{\curly{var  $\vert$
{\rm (}\curly{var $\vert$ {\rm (}keyword var{\rm )}}
\ttbrac{initform \brac{supplied-p-parameter} }{\rm )}}}\cr
\+&&&\brac{\tt\&allow-other-keys} {\tt ]} \cr
\+&&\ttbrac{{\tt\&aux} \star{\curly{var $\vert$ {\rm (}var \brac{initform} {\rm )}}}} {\rm )} \cr
\Vskip1pc!\null
\+&{\it specializer\/}::$=$ {\it symbol} $\vert$ {\rm (}{\tt quote} {\it datum}{\rm )}\cr
\Vskip 1pc!

\label Arguments:

The {\it name\/} argument is a non-{\bf nil} symbol that
names the generic function on which the method is defined.

Each {\it method-qualifier\/} is an object that is used
by method combination to identify the given method.  A method
qualifier is a non-{\bf nil} atom.  The method 
combination type may further restrict what a method qualifier
may be.  The standard method combination type allows for unqualified 
methods (no {\it method-qualifiers\/}), or exactly one of the following 
keywords as the sole qualifier:  {\bf :before}, {\bf :after}, {\bf :around}.

The {\it specialized-lambda-list\/} argument is like an ordinary
function lambda list except that parameters for required arguments may
be replaced by specialized parameters.  A specialized parameter is a
list of the form {\tt ({\it variable-name parameter-specializer\/})}.  Only
required parameters may be specialized.
A parameter specializer
is a symbol that names a user-defined class, a structure defined by
{\bf defstruct} if the {\bf :type} option was not used, or a class
that corresponds to a Common Lisp type specifier.   Note that
not all Common Lisp types have a corresponding
class.   A parameter specializer can also be {\tt (quote {\it object\/})}.
Such a parameter specializer indicates that the corresponding argument must
be {\bf eql} to the quoted object for the method to be applicable.  
If no parameter specializer is specified for a given required parameter,
the parameter specializer for that parameter defaults to {\bf t}.
A method all of whose required arguments have {\bf t} parameter 
specifiers is termed a {\bit default method}.  Such a method is selected
when no more specific method for the generic function is applicable.

\label Values:

The result of {\bf defmethod} is the method object.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

The class of the method object that is created is that given by the 
method class option of the generic function on which the method is defined.

If a method already exists on the given generic function with the same 
parameter specializers and the same qualifiers, {\bf defmethod} replaces
the existing method with the one now being defined. 

\label See Also:

{\bf get-method

lambda-list-specializers}

``Congruent Lambda-lists for all Methods of a Generic Function'' 

\endcom


\begincom{defmethod-setf}\ftype{Macro}

\label Purpose:

The macro {\bf defmethod-setf} defines a method for a setf generic
function.  A setf generic function is called in an expression such as: 
{\tt (setf ({\it name arguments\/}) {\it new-value\/})}.  

\label Syntax:

\Defmac {defmethod-setf} {name
\vtop{\hbox{\star{\curly{method-qualifier\/}}}
\hbox{specialized-lambda-list specialized-setf-lambda-list}
\hbox{\star{\curly{declaration $\vert$ documentation}} \star\form}}}
\Vskip1pc!\null
{\it name\/}::$=$ {\it symbol}
\Vskip1pc!\null
{\it method-qualifier\/}::$=$ {\it symbol}
\Vskip1pc!\null
\settabs\+\hskip\leftskip&\cr
\+&{\it specialized-lambda-list\/}::$=$ (&\star{\curly{var  $\vert$ {\rm (}var specializer\/{\rm )}}}  \cr
\+&&\ttbrac{{\opt} \star{\curly{var $\vert$ {\rm (}var \ttbrac{initform {\brac{supplied-p-parameter}} }{\rm )}}}}  \cr
\+&&\ttbrac{{\tt\&rest} {\it var\/}} \cr
\+&&{\tt [}{\key{}}&\star{\curly{var  $\vert$
{\rm (}\curly{var $\vert$ {\rm (}keyword var{\rm )}}
\ttbrac{initform \brac{supplied-p-parameter} }{\rm )}}}\cr
\+&&&\brac{\tt\&allow-other-keys} {\tt ]} \cr
\+&&\ttbrac{{\tt\&aux} \star{\curly{var $\vert$ {\rm (}var \brac{initform} {\rm )}}}} {\rm )} \cr
\Vskip1pc!\null
\+&{\it specialized-setf-lambda-list\/}::$=$ (\curly{var  $\vert$ {\rm (}var specializer\/{\rm ))}}  \cr
\Vskip1pc!\null
\+&{\it specializer\/}::$=$ {\it symbol} $\vert$ {\rm (}{\tt quote} {\it datum}{\rm )}\cr
\Vskip 1pc!

\label Arguments:

The arguments {\it name\/}, {\it method-qualifier\/}, and {\it
specialized-lambda-list\/} are the same as for {\bf defmethod}. 

The {\it specialized-setf-lambda-list\/} argument is the same as {\it
specialized-lambda-list\/} except that for now there can be only one
parameter.  In other words, {\it specialized-setf-lambda-list\/} is a
lambda list containing exactly one required parameter, which may be
specialized.  

The {\it var\/} argument in the {\it specialized-setf-lambda-list\/}
argument is the name of the variable that gets bound to the value of
the {\it new-value\/} form in the expression {\tt (setf {\it place
new-value})}.
 
\label Values:

The result of {\bf defmethod-setf} is the method object.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

If a method already exists on the given generic function with the same 
parameter specializers and the same qualifiers, {\bf defmethod} replaces
the existing method with the one now being defined. 

\label See Also:

{\bf defmethod}

\endcom



\begincom{describe}\ftype{Generic function}

\label Purpose:

The Common Lisp function {\bf describe} is replaced by a generic
function.  The generic function {\bf describe} prints information
about a given object on the standard output.

Each implementation is required to provide a default method for {\bf
describe}; that is, a method for the class {\bf t}.  Implementations
are free to add methods for specific classes.  Users can write methods
for {\bf describe} for their own classes if they do not wish to
inherit an implementation-supplied method.  These methods must conform
to the definition of {\bf describe} as specified in {\it Common Lisp
the Language}.

\label Syntax:

\Defgen {describe} {object}

\label Arguments:

The argument of {\bf describe} may be any Common Lisp object. 

\label Values:

The function {\bf describe} returns no values.

\label Examples:

\screen!

[To be written.]
\endscreen!

\endcom



\begincom{documentation}\ftype{Generic Function}

\label Purpose:

The Common Lisp function {\bf documentation} is replaced by a generic
function.  The generic function {\bf documentation} returns the
documentation string associated with the given object if it is
available, otherwise it returns {\bf nil}.

\label Syntax:

\Defgen documentation {x {\opt} doc-type}

\label Arguments:

The first argument is a generic function object, a method object, a class
object, or a symbol.   

If the first argument is a generic function object, method object, or class
object, {\bf documentation} returns the documentation string for that 
object.

If the first argument is not a symbol, the second argument must not be
supplied. 

If the first argument is a symbol, the second argument must be
supplied.  {\bf documentation} returns the documentation string of 
the given type.  The {\it doc-type\/} argument is a symbol.  It can be
one of the following types: {\bf variable}, {\bf function}, {\bf
structure}, {\bf type}, and {\bf setf}.

If the first argument is a symbol naming a class and the 
second argument is {\bf type}, {\bf documentation} returns 
the documentation string of the class object named by the symbol.   

If the first argument is a symbol naming a function or generic funcion 
and the second argument is {\bf function}, 
{\bf documentation} returns the documentation string of the function 
or generic function named by the symbol.  

If the first argument is a symbol naming a generic function 
and the second argument is {\bf setf}, 
{\bf documentation} returns the documentation string of the 
setf generic function called in an expression such as 
{\tt (setf ({\it generic-function-name arguments}) {\it new-value})}.

If no documentation is associated with the given object, {\bf documentation}
returns {\bf nil}.

\label Values:

The documentation string associated with the given object is returned
unless none is available, in which case {\bf documentation} returns
{\bf nil}.

\label Remarks:

The macro {\bf setf} can be used with {\bf documentation} to update the
documentation for a symbol, generic function object, method object, or class object.

\endcom



%\begincom{generic-function-lambda-list}\ftype{Generic function}
%
%\label Purpose:
%
%The generic function {\bf generic-function-lambda-list} returns the
%lambda list of its argument from which default values for {\bf
%\&optional} and {\bf \&key} parameters and supplied-p parameters have
%been removed.
%
%\label Syntax:
%
%\Defgen {generic-function-lambda-list} {function-or-generic-function}
%
%\label Arguments:
%
%The argument to {\bf generic-function-lambda-list} is either a
%function, a symbol that names a function, or a generic function.
%If it is a generic function, it is in one of
%these forms: a generic function object; a symbol that names a generic
%function; or a list that names a {\bf setf} generic function, such as
%({\bf setf} {\it symbol\/}).
%
%\label Values:
%
%The result of {\bf generic-function-lambda-list} is a copy of the
%lambda list of its argument from which default values for {\bf
%\&optional} and {\bf \&key} parameters and supplied-p parameters have
%been removed.
%
%\label Examples:
%
%\screen!
%
%[To be written.]
%\endscreen!
%
%\label Remarks:
%
%There is a related function named {\bf function-parameters} that is
%being considered for Common Lisp.
%
%\endcom
%
% 
%\begincom{generic-function-method-combination-type}\ftype{Generic function}
%
%\label Purpose:
%
%The generic function {\bf generic-function-method-combination-type}
%returns the method combination type for the given generic function.
%
%[The details of this function are currently under discussion.]
%
%\label Syntax:
%
%\Defgen {generic-function-method-combination} {generic-function}
%
%\label Arguments:
%
%The {\it generic-function\/} argument is either a generic function
%object; a symbol that names a generic function; or a list that names a
%{\bf setf} generic function, such as ({\bf setf} {\it symbol\/}). 
%
%\label Values:
%
%\label Examples:
%
%\screen!
%
%[To be written.]
%\endscreen!
%
%\endcom


%\begincom{generic-function-p}\ftype{}
%
%\label Purpose:
%
%The predicate {\bf generic-function-p} is true if its argument is a
%generic function, otherwise it is false.
%
%\label Syntax:
%
%\Defun {generic-function-p} {object}
%
%\label Values:
%
%A non-{\bf nil} value is returned if the argument is a generic function
%object, otherwise the result is {\bf nil}.
%
%\label Examples:
%
%\screen!
%\endscreen!
%
%\endcom



\begincom{get-method}\ftype{Generic function}

\label Purpose:

The generic function {\bf get-method} takes a generic function and returns the
method object that is identified by having the specified 
method qualifiers in the given order, and the specified 
parameter specializers.  If no such method exists, {\bf get-method}
signals an error.   

\label Syntax:

\Defgen {get-method} {generic-function method-qualifiers specializers}

\label Arguments:

The {\it generic-function\/} argument specifies a generic function.  It
is one of the following: a generic function 
object; a symbol that names a generic function; or a list that names a
setf generic function, such as {\tt (setf {\it symbol\/})}. 
An error is signalled if no such generic function exists or if the 
the first argument specifies a non-generic function, a macro,
or a special form.
% (even if the {\it specializers\/} argument indicates a request for a default
% method; see below). 

The {\it method-qualifiers\/} argument is a list of the
method qualifiers for the method.   The order of the {\it method-qualifiers\/} 
is significant.  

The {\it specializers\/} argument is a list of the parameter
specializers for the method.  It must correspond in length to the number
of required arguments of the generic function.  This means that to
obtain the default method for a given generic function, a list of {\bf
t}'s corresponding in length to the number of required arguments of that
generic function must be given.  

%If {\it specializers\/} is {\bf nil}, the
%default method function for that generic function is returned.

\label Values:

The result of {\bf get-method} is the method object with the given
method qualifiers and parameter specializers.  If no such
method object exists, {\bf get-method} signals an error.

\label Examples:

\screen!

[To be written.]
\endscreen!

\endcom


\begincom{get-setf-generic-function}\ftype{Function}

\label Purpose:

The function {\bf get-setf-generic-function} takes a symbol for which
a setf generic function has been defined by either {\bf
defmethod-setf} or {\bf defgeneric-options-setf} and returns a generic
function object.  This object is the generic function that is called
when the {\tt (setf ({\it name arguments\/}) {\it new-value\/})} is invoked.

%[More details to be provided by Gregor.]

\label Syntax:

\Defun {get-setf-generic-function} {name}

\label Arguments:

The {\it name\/} argument is a symbol for which a setf generic
function has been defined.  If no such setf generic function has been
defined, an error is signalled.

\label Values:

The function {\bf get-setf-generic-function} returns a generic function
object.  This object is the generic function that is called
when the {\tt (setf ({\it name arguments\/}) {\it new-value\/})} is invoked. 

\label Examples:

\screen!

[To be written.]
\endscreen!

\endcom



\begincom{invalid-method-error}\ftype{Function}

\label Purpose:

The function {\bf invalid-method-error} reports an applicable method
whose qualifiers are not valid for the method combination type.  The 
error message is constructed using a format string and any arguments to it. 
An implementation may add additional contextual information 
to the error message, thus {\bf invalid-method-error} should be called
only from the dynamic environment of a method-combination function.

The implementation determines whether {\bf invalid-method-error} returns to its
caller or throws.

\label Syntax:

\Defun {invalid-method-error} {method format-string {\rest} args}

\label Arguments:

The {\it method\/} argument is the invalid method object.  

The {\it format-string\/} argument is a control string that can be
given to {\bf format}, and {\it args\/} are any arguments required by
that string.

\label Remarks:

The function {\bf invalid-method-error} is called automatically when a
method fails to satisfy every qualifier pattern and predicate in a
{\bf define-method-combination} form. 
A method combination function that 
imposes additional restrictions should call {\bf invalid-method-error}
explicitly if it encounters a method it cannot accept.

The function {\bf invalid-method-error} will use the condition
signalling system when and if it is adopted into Common Lisp.

\endcom




%\begincom{lambda-list-specializers}\ftype{Function}
%
%\label Purpose:
%
%The function {\bf lambda-list-specializers} takes an ordinary lambda
%list or a specialized lambda list and returns a list containing the
%parameter specializers for all required arguments.  The specializer
%{\bf t} is returned for any required lambda list argument for which no
%parameter specializer was given.
%
%\label Syntax:
%
%\Defun {lambda-list-specializers} {specialized-lambda-list}
%
%\label Values:
%
%The result of {\bf lambda-list-specializers} is a list of the parameter
%specializers for all required arguments in the given lambda list.
%
%\endcom


\begincom{make-generic-function}\ftype{Function}

\label Purpose:

The function {\bf make-generic-function} creates and returns a generic
function.  This resulting function can be used an argument to
{\bf funcall} and {\bf apply}.

\label Syntax:

\Defun {make-generic-function} {\key \vtop{\hbox{ :lambda-list :argument-precedence-order}
\hbox{ :declare :documentation :method-combination} 
\hbox{ :generic-function-class :method-class}}}

\label Arguments:

The {\bf :lambda-list} argument is a lambda list of the type that may be
given to {\bf defgeneric-options}.   

The following arguments have the same semantics as the corresponding
arguments of {\bf defgeneric-options} although their syntax may differ:

\beginlist

\item{\bull}
The {\bf :argument-precedence-order} argument is a list containing the
parameter names for all required arguments.  
Each required argument should be included exactly once as a {\it
parameter-name}, so the full and unambiguous precedence order is
supplied.   If this condition is not met an error is signalled.

\item{\bull}
The {\bf :method-combination} argument is a symbol or list, whose 
car is a symbol and crd is any arguments accepted by the method combination.
The symbol names a type of method combination.   Any arguments that follow 
that symbol depend on the type of method combination.   
Note that the standard method combination type does not support any arguments.
However, all types of method combination defined by the short form of {\bf 
define-method-combination} accept an optional argument named {\it 
order\/}, defaulting to {\bf :most-specific-first}.  A value of {\bf
:most-specific-last} reverses the order of the primary methods, without
affecting the order of the auxiliary methods. 

\item{\bull}
The {\bf :documentation} argument is a string.

\item{\bull}
The {\bf :declare} argument is a list of declaration specifiers.

\item{\bull}
The {\bf :generic-function-class} argument is a class or the name of a class.

\item{\bull}
The {\bf :method-class} argument is a class or the name of a class.
\endlist


\label Values:

The result of {\bf make-generic-function} is a generic function object.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

The function {\bf make-generic-function} is the
programmatic interface to {\bf defgeneric-options}.

\label See Also:

{\bf defgeneric-options}

\endcom

\begincom{make-instance}\ftype{Function}

\label Purpose:

The function {\bf make-instance} creates and returns a new instance of
the class {\it class}.

\label Syntax:

\Defun {make-instance} {class {\rest} initialize-keywords-and-values}

\label Arguments:

The {\it class\/} argument is a class object or a symbol that names a class.

\label Values:

The new instance is returned.

\label Remarks:

[Discussion of initialization to go here.]

It is not possible to make an instance of a class whose class is
{\bf standard-type-class} using the function {\bf make-instance}.  
If {\it class} is an instance of {\bf standard-type-class}, 
{\bf make-instance} signals an error.

%Removed because the :instantiable option was removed.  -Sonya
%If we put it back, note that the name of the option is changed. -Sonya 
%It is not possible to make an instance of a class created with {\bf
%defclass} if the {\bf :instantiable} option was {\bf nil}.  An error is
%signalled in this case. 

The function {\bf class-of} can be used to determine the class of the
instance that is returned.

\label See Also:

{\bf class-of}

\endcom



\begincom{make-method}\ftype{Function}

\label Purpose:

The function {\bf make-method} creates and returns a method object.

\label Syntax:

\Defun {make-method} {method-qualifiers specializers function}

\label Arguments:

The {\it method-qualifiers\/} argument is a list of the method
qualifiers for the method.
%A method qualifier is a non-{\bf nil} symbol.

The {\it specializers\/} argument is a list of the parameter
specializers for the method.

The {\it function\/} argument is the method function.  

The length of the list of specializers must be equal to
the number of required arguments of the method function.

\label Values:

The function {\bf make-method} returns the resulting method object.
\label Examples:

\screen!

[To be written.]
\endscreen!

\label See Also:

{\bf defmethod

add-method}

\endcom


\begincom{make-method-call}\ftype{Function}

\label Purpose:

The function {\bf make-method-call} is used in method combination.  It
can be called only from the dynamic environment of a method combination 
function, that is, from the body of a {\bf define-method-combination} form
% from a {\bf compute-effective-method} method, --removed reference to
% meta-object protocol function --lgd
or from a function called by it.

The function {\bf make-method-call} returns a form whose car is
the operator specified by the {\bf :operator} keyword argument
(default is {\bf progn}) and whose cdr is a list of forms that
call the methods in {\it method-list}.  Each method receives the same
arguments that the generic function received.  The function
{\bf make-method-call} hides the implementation-dependent details of
how methods are called.

\label Syntax:

\Defun {make-method-call} {method-list {\key :operator :around :identity-with-one-argument}}

\label Arguments:

Each element of {\it method-list\/} can be either a method object or a list.
When a list is given, it is regarded as a form and converted when necessary
into a method whose body is that form (conceptually by enclosing it in a 
lambda expression).
% Is there any clearer way to state this parenthetical remark?

If {\bf :around} is true and the length of {\it method-list\/}
is greater than 1, the result is a form that calls the first method and
arranges for {\bf call-next-method} to reach the rest of the methods in the
order in which they appear in {\it method-list}.  If {\bf :around} is 
true, {\bf :operator} must not be specified.  The default value of
{\bf :around} is {\bf nil}.

If {\bf :identity-with-one-argument} is true and {\it
method-list\/} contains exactly one element, the result is simply a
form that calls that single method and does not invoke the
operator.  If {\bf :operator} is {\bf progn}, the default for {\bf
identity-with-one-argument} is true; otherwise the default for this
option is false.  This option is to be used with operators that are
identity operators when applied to one argument, that is, such
operators as {\bf progn}, {\bf and}, {\bf $+$} and {\bf max}.  This
optimization can enable the use of an existing method as the
effective method, avoiding the need to create a new effective method.
The \OS's optimizer already knows about {\bf progn},
{\bf multiple-value-prog1}, and {\bf multiple-value-prog2}, but
{\bf :identity-with-one-argument} can be used to tell it about
other operators.

If {\it method-list\/} is {\bf nil}, the result is a call to
the specified operator with no arguments or a form with the same effect.

As a convenience, if {\it method-list\/} is a method object, it is
automatically converted to a one-element list of that method.

\vfill\eject
\label Values:

The result is a form whose car is the operator specified by the 
{\bf :operator} keyword argument and whose cdr is a list of forms
that call the methods in {\it method-list}.

\label See Also: 

See ``Declarative Method Combination.'' 

\label Possible Extensions:

Additional keyword arguments will be needed if {\bf call-next-method}
is allowed to change the arguments passed on to the next method.  They
will be proposed separately. 

\endcom


\begincom{method-combination-error}\ftype{Function}

\label Purpose:

The function {\bf method-combination-error} reports a problem in method
combination.   The error message is constructed using a format string
and any arguments to it.  An implementation may add additional
contextual information to the error message, thus {\bf
method-combination-error} should be called only from the dynamic
environment of a method combination function.

The environment determines whether {\bf method-combination-error} returns
to its caller or throws.

\label Syntax:

\Defun {method-combination-error} {format-string {\rest} args}

\label Arguments: 

The {\it format-string\/} argument is a control string that can be
given to {\bf format}, and {\it args\/} are any arguments required by
that string.

\label Remarks:

The function {\bf method-combination-error} will use the condition
signalling system when and if it is adopted into Common Lisp.

\label See Also: 

See ``Declarative Method Combination.'' 

\endcom



\begincom{method-qualifiers}\ftype{Function}

\label Purpose:

The function {\bf method-qualifiers} returns a list of the qualifiers
of the given method.  This is particularly useful
when the body forms perform additional filtering or processing of the
method-group lists. 

% I don't understand sentence-2 here (i.e., what is meant by ``the body'').
% Is it possible to say: ``This function is particularly useful in
% filtering or processing method-group lists''?

\label Syntax:

\Defun {method-qualifiers} {method}

\label Arguments:

The {\it method\/} argument is a method object. 

\label Values:

A list of the qualifiers of the given method is returned.

\label Examples:

\screen!

(setq methods (remove-duplicates methods
                                 :from-end t
                                 :key #'method-qualifiers
                                 :test #'equal))

\endscreen!

\label See Also: 

See ``Declarative Method Combination.'' 

\endcom

 
\begincom{multiple-value-prog2}\ftype{Macro}

\label Purpose:

The macro {\bf multiple-value-prog2} is the obvious extension of 
{\bf multiple-value-prog1}.  It evaluates the given forms and returns
all the values of {\it result-form}. 

\label Syntax:

\Defmac {multiple-value-prog2} {form result-form \star{\curly{form}}}

\label Values:

All the values of {\it result-form\/} are returned.

\label See Also: 

See ``Declarative Method Combination.'' 

\endcom



\begincom{print-object}\ftype{Generic function}

\label Purpose:

The generic function {\bf print-object} outputs the printed
representation of an object onto a stream.  The function {\bf
print-object} is called by the print system; it should not be called
by the user.

Each implementation is required to provide a default method for {\bf 
print-object}; that is, a method for the class {\bf t}.  Implementations 
are free to add methods for specific classes.  Users can write methods 
for {\bf print-object} for their own classes if they do not wish to 
inherit an implementation-supplied method. 

\label Syntax:

\Defgen {print-object} {object stream}

\label Arguments:

The first argument is any Lisp object.   The second argument is a
stream; it cannot be {\bf t} or {\bf nil}. 

\label Values:

The function {\bf print-object} returns its first argument, the object.  

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

Methods for {\bf print-object} must obey the print control special
variables described in {\it Common Lisp the Language}.  The
specific details are:

\beginlist

\item{\bull}
Each method must implement {\bf *print-escape}*. 

\item{\bull} 
The {\bf *print-pretty*} control variable can be ignored
by most methods other than the one for lists.

\item{\bull}
The {\bf *print-circle*} control variable is handled by the printer
and can be ignored by methods.

\item{\bull}
The printer takes care of {\bf *print-level*} automatically, provided that
each method handles exactly one level of structure and
calls {\bf write} (or an equivalent function) recursively if
there are more structural levels.  The printer's decision
of whether an object has components (and therefore should
not be printed when the printing depth is not less than
{\bf *print-level*}) is implementation-dependent.  In some
implementations its {\bf print-object} method is not called, in
others the method is called and the determination that the
object has components is based on what it tries to output
to the stream.

\item{\bull}
Methods that produce output of indefinite length must obey
{\bf *print-length*}, but most methods other than the one for lists can
ignore it.

\item{\bull}
The {\bf *print-base*}, {\bf *print-radix*}, {\bf *print-case*}, {\bf
*print-gensym*}, and {\bf *print-array*} control variables apply
to specific types of objects and are handled by the methods for those
objects.

\endlist

In general, the printer and the {\bf print-object} methods should not
rebind the print control variables as they recurse through the
structure, but this is necessarily implementation-dependent.

In some implementations the stream argument passed to a {\bf
print-object} method is not the original stream, but is an
intermediate stream that implements part of the printer.  Methods
should therefore not depend on the identity of this stream.

All of the existing printing functions ({\bf write}, {\bf prin1}, {\bf
print}, {\bf princ}, {\bf pprint}, {\bf write-to-string}, {\bf
prin1-to-string}, {\bf princ-to-string}, the {\tt ~}{\bf S} and {\tt
~}{\bf A} format operations, and the {\tt ~}{\bf B}, {\tt ~}{\bf D},
{\tt ~}{\bf E}, {\tt ~}{\bf F}, {\tt ~}{\bf G}, {\tt ~}{\bf \$}, {\tt
~}{\bf O}, {\tt ~}{\bf R}, and {\tt ~}{\bf X} format operations when they
encounter a non-numeric value) are required to be changed to go
through the {\bf print-object} generic function.  Each implementation is
required to replace its former implementation of printing with one or
more {\bf print-object} methods.  Exactly which classes have methods for
{\bf print-object} is not specified; it would be valid for an implementation
to have one default method that is inherited by all system-defined
classes.

\endcom


%\begincom{remove-class}\ftype{}
%
%\label Purpose:
%
%\label Syntax:
%
%\Defun {remove-class} {class}
%
%\label Arguments:
%
%\label Values:
%
%\label Examples:
%
%\endcom



\begincom{remove-method}\ftype{Generic function}

\label Purpose:

The generic function {\bf remove-method} removes a method from a
generic function.  It destructively modifies the specified generic
function and returns the modified generic function as its result.  If
the specified method is not a method of the generic function, an error is
signalled.

\label Syntax:

\Defgen {remove-method} {generic-function method}

\label Arguments:

The {\it generic-function\/} argument specifies a generic function
object.  It is one of the following: a generic function object; a
symbol that names a generic function; or a list that names a
setf generic function, such as {\tt (setf {\it symbol\/})}.  An error
is signalled if no such generic function exists.

The {\it method\/} argument is a method object.  

\label Values:

The function {\bf remove-method} returns the modified generic
function.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

\label See Also:

{\bf
get-method

add-method}

\endcom



%\begincom{remove-setf-method}\ftype{Function}
%
%\label Purpose:
%
%The function {\bf remove-setf-method} removes the {\bf setf} method
%for the given name, method qualifiers, and parameter
%specializers from the corresponding generic function.
%
%The method {\bf remove-setf-method} returns the given method object if it 
%succeeds and {\bf nil} if there is no such method.
%
%\label Syntax:
%
%\Defun {remove-setf-method} {generic-function method-qualifiers
%specializers setf-specializers}
%
%\label Arguments:
%
%The {\it generic-function\/} argument is a generic function or the name
%of a generic function.
%
%The {\it method-qualifiers\/} argument is a list of the
%method qualifiers for the method.
%
%The {\it specializers\/} argument is a list of
%the parameter specializers for the arguments of the
%method that is to be removed.  If the {\it specializers\/}
%list contains fewer elements than the lambda list of the corresponding
%generic function, the remaining elements are considered to be {\bf t}.
%
%The {\it specializers\/} list can be obtained from a
%{\bf defmethod} lambda list by use of the function 
%{\bf lambda-list-specializers}.
%
%\label Values:
%
%The result of {\bf remove-setf-method} is the method object with the
%given method qualifiers and parameter specializers.  If
%no such method object exists, {\bf remove-setf-method} returns {\bf
%nil}.
%
%\label See Also:
%
%{\bf lambda-list-specializers
%
%remove-method
%
%defmethod}
%
%\endcom


\begincom{slot-value}\ftype{Function}

\label Purpose:

The function {\bf slot-value} returns the value contained in the slot
{\it slot-name\/} of the given object.   If there is no slot with that
name, or if there is a slot whose allocation type is {\bf :none}, 
an error is signalled. 

The macro {\bf setf} can be used with {\bf slot-value} to change the value
of a slot. 

\label Syntax:

\Defun {slot-value} {object slot-name}

\label Examples:

\screen!

[To be written.]
\endscreen!


\endcom


\begincom{with-slots}\ftype{Macro}

\label Purpose:

The macro {\bf with-slots} creates a lexical context for referring to
slots as though they were variables.  Within such a context the value
of the slot can be specified by using its slot name, as if it were a
lexically bound variable.  Both {\bf setf} and {\bf setq} can be used
to set the value of the slot.  The macro {\bf with-slots} can be used
inside a method or inside of any function.

The macro {\bf with-slots} translates an appearance of the slot name as
a variable into a call to the accessor generated by {\bf defclass}
unless the {\bf :use-accessors} argument is {\bf nil}, in which 
case {\bf slot-value} is used instead of the accessor. 

\label Syntax:  

\Defmac {with-slots} {\paren {\star{\curly{instance-form $\vert$ \paren{instance-form \star{option}}}}} \star{\form}}

{\it option\/}::$=$  {\tt\vtop{\hbox{:use-accessors {\it flag\/} $\vert$}
\hbox{:class {\it class-name\/} $\vert$}
\hbox{:prefix {\it prefix-string\/}}}}

\label Arguments:

The {\it instance-form\/} should evaluate to an object that has slots,
such as an instance of a user-defined class.   An instance of 
{\bf standard-type-class} does not have slots. 

Each {\it instance-form\/} is evaluated exactly once, upon entry to the 
body of the {\bf with-slots} form.  The {\it instance-form\/} forms 
are evaluated in the order in which they appear.  

It is necessary that the class of the instance can be determined lexically 
(at compile-time).  
Either {\it instance-form\/} must be the name of a specialized parameter in
the lambda-list of a method lexically containing this {\bf with-slots}
form, or the {\bf :class} option must be used to indicate the class of
the instance.

The keyword options in this special form are not evaluated.  These are
the keyword options:  

\beginlist

\item{\bull}
The {\bf :class} option is used to specify the class or a superclass
of the instance.  Its argument is the name of a class.  This option is
necessary if the class of the instance cannot be determined from the
lambda list of a method lexically containing the {\bf with-slots}
form or if the {\bf with-slots} form does not occur within a method
body.  If the {\bf :class} option is used an error is signalled at runtime if the
class of the instance is not a subclass of the specified class.   Note that
if a superclass of the instance is given here, only those slots accessible
to instances of the superclass are accessible; this might be different set
of slots than those accessible by the instance itself. 

\item{\bull}
The {\bf :prefix} option is used to generate a variable name by which
the given slot may be referenced.
This name is given by {\it prefix-string\/} followed by the slot 
name.  It causes a symbol of the given name to be created and interned
in the package that is current at the time the {\bf with-slots} form is
macro-expanded. 
This option can be used to keep separate two instances whose slot names
overlap, such as two instances of the same class or two instances that
have a common superclass.

\item{\bull}
The {\bf :use-accessors} option is used to specify whether accessing a
slot is performed using the accessor function generated by {\bf defclass}
or by the function {\bf slot-value}.  If {\bf :use-accessors} is {\bf t},
the accessor function generated by {\bf defclass} is used to access the slots; this
means that any methods written for the accessor are also run.
If {\bf :use-accessors} is {\bf nil}, {\bf with-slots} accesses the
slots using {\bf slot-value} instead of the accessor.
If accessors for the slot were not specified in the relevant {\bf defclass}
form, then the value of {\bf :use-accessors} should be specified as {\bf nil}.
The default value of {\bf :use-accessors} is {\bf t}.

\endlist

\label Values:

The value of the {\bf with-slots} form is the value returned by
the last form in its body. 

\label Examples:

\screen!

(defclass point () ((x 0) (y 0))
  (:accessor-prefix point-))

(defmethod move ((p point) dx dy)
  (with-slots (p)  ; p is known as a point from the method args
    (setf x (+ x dx) y (+ y dy))))       ; use accessor functions

(defmethod move ((p point) dx dy)
  (with-slots ((p :use-accessors nil))
    (setf x (+ x dx) y (+ y dy))))       ; use slot-value  
 
(defmethod make-same-height ((p1 point) (p2 point))
  ;; use :prefix to make distinction between the two points
  (with-slots ((p1 :prefix p1-) (p2 :prefix p2-))  
    (setf p1-y p2-y)))

(defmethod make-horizontal ((l line))
  ;; point is a component class of line
  ;; it is necessary to specify the class of point explicitly,
  ;; because there is no lexical way to determine it 
  (with-slots (((left-point l) :class point :prefix left-)
               ((right-point l) :class point :prefix right-))
    (setf left-y right-y)))

\endscreen!

\label Remarks:

The examples have used {\bf setf} to change the value of instance
variables; {\bf setq} is also allowed.  

An error is signalled if the class of {\it instance} cannot be inferred
from the lexical context in which it occurs, and the {\bf :class} option 
is not specified.

An error is signaled if there is any conflict between variable names. 

\endcom
\endChapter
\bye